Anonymous usage telemetry

ActionRail sends a small amount of anonymous usage telemetry to help the maintainers understand whether the Console and SDK are being used. Telemetry is not part of enforcement, Source grounding, audit delivery, or human review.

The receiver is https://hub.actionrail.ai/v1/events.

Events

Event	When it is sent	Properties
console_started	Once when a local Console process starts successfully.	None.
sdk_initialized	At most once per SDK mode in a process.	mode: instrument, monitor, or enforce.
usage_summary	At most once per UTC day from the Console.	One snapshot date and the exact aggregate counters listed below.

Every event has this fixed envelope:

Field	Value
schema_version	Integer event-schema version.
event_id	Random UUID for transport deduplication.
anonymous_id	Random installation UUID generated locally.
event	One of the three event names above.
occurred_at	UTC client timestamp.
component	sdk or console.
version	Installed ActionRail package version.
python_version	Python major and minor version only.
platform	Operating-system family, such as linux or darwin.
properties	The event-specific allowlisted fields above.

ActionRail telemetry does not send agent IDs, agent keys, tool names, rules, prompts, arguments, individual decisions, Source types, Source configuration, endpoints, credentials, data-directory paths, database contents, audit records, or error messages.

Usage summary counters

The Console derives the summary locally from its SQLite database. The counters are exact totals of records currently retained in that Console data directory, not a stream of individual actions:

Property	Definition
snapshot_date	UTC date represented by the snapshot.
agents_total	Agents currently configured in the Console.
active_agents_total	Configured agents that have ever reported an observed call or evaluated action.
tool_calls_observed_total	Tool calls observed through instrument().
actions_evaluated_total	Action decisions reported in monitor or enforce mode.
actions_monitored_total	Evaluations made in monitor mode, where ActionRail did not enforce the verdict.
actions_allowed_total	Enforced evaluations allowed immediately.
actions_blocked_total	Enforced evaluations blocked before tool execution.
actions_held_total	Enforced evaluations held for human review.

All counters are exact non-negative integers. Totals can decrease if local agents or activity are deleted. A daily snapshot lets the maintainers measure adoption and changes over time without sending per-agent or per-action records.

Anonymous installation identifier

The identifier is a random UUID and is not derived from a hostname, username, email address, MAC address, agent identity, or credential. With the default local layout, the SDK and Console share ~/.actionrail/.anonymous_id so one installation is not double-counted.

Deleting that file creates a new identifier on the next eligible event. Custom SDK and Console data directories keep their identifier in that directory.

Disable telemetry

Set the following environment variable before starting the Console or agent process:

export ACTIONRAIL_TELEMETRY_DISABLED=1

The values 1, true, yes, and on are accepted case-insensitively. ActionRail also disables telemetry when DO_NOT_TRACK is enabled, while running under pytest, or when CI is enabled.

Failure behavior

Telemetry delivery is deliberately isolated from audit delivery:

• it runs on a daemon thread;
• it has a one-second network timeout;
• lifecycle events have no retry loop, batch, disk queue, or shutdown flush;
• the Console keeps at most one aggregate-only usage_summary in ~/.actionrail/.usage_telemetry.json and retries it on the next hourly check;
• a successfully delivered summary is not sent again for the same UTC date;
• every network, filesystem, and serialization failure is ignored;
• it cannot change an enforcement decision or prevent application startup.

The pending summary contains only the documented counters and coarse event envelope. It does not contain individual activity. Audit events use a separate durable outbox because losing them affects the product contract; anonymous product telemetry does not receive that treatment.